#!/usr/bin/python2.4
#
# Copyright 2008 Google Inc.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.


"""spiral's ranking module.

spiral aims to be a faster and nicer packages.debian.org replacement.
"""

__author__ = 'stratus@google.com (Gustavo Franco)'


class Ranking(object):
  """This class contains helpers methods for ranking results.

  Ranking may be used in conjuntion with list.sort() and the following
  declared comparison methods in this module.
  ie.:
    rank = self.Ranking(keyword)
    list.sort(cmp=rank.SortBySubstring, key=operator.itemgetter('name'))

  Attributes:
    keyword: string containing a keyword to be ranked.
  """

  def __init__(self, keyword):
    """Inits Ranking with keyword."""
    self.keyword = keyword

  def SortByExactmatch(self, x, unused_y):
    """list.sort() helper function to sort by exact match.

    sortby_exactmatch takes x and y of each list from list's sort method
    and make a exact match comparison against keyword. When x matches
    keyword it wins.

    Args:
      x: a string - automagically passed by list.sort().
      unused_y: a string - automagically passed by list.sort().

    Returns:
      -1: When x matches keyword.
      0: When x doesn't match keyword.
    """
    if x == self.keyword:
      return -1
    else:
      return 0

  def SortBySubstring(self, unused_x, y):
    """list.sort() helper function to sory by substring match.

    sortby_substringmatch takes x and y of each list from list's sort method
    and make a string.find() call against a keyword. When y contains keyword
    it wins.

    Args:
      unused_x: a string - automagically passed by list.sort().
      y: a string - automagically passed by list.sort().

    Returns:
      -1: When y contains keyword.
      0: When y doesn't contain keyword.
    """
    if y.find(self.keyword):
      return -1
    else:
      return 0

  def SortByVotes(self, x, y):
    """list.sort() helper function to sort by votes.

    sortby_votes takes x and y of each list from list's sort method and check
    which one is greater since both are votes.

    Args:
      x: integer - automagically passed by list.sort().
      y: integer - automagically passed by list.sort().

    Returns:
      -1: When x is greater than y.
      0: When x and y are equal or x is less than y.
    """
    if x > y:
      return -1
    else:
      return 0
